home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / hist_equal.pro < prev    next >
Text File  |  1997-07-08  |  5KB  |  139 lines
  1. ; $Id: hist_equal.pro,v 1.6 1997/01/15 03:11:50 ali Exp $
  2. ;
  3. ; Copyright (c) 1982-1997, Research Systems, Inc.  All rights reserved.
  4. ;    Unauthorized reproduction prohibited.
  5.  
  6. FUNCTION HIST_EQUAL, A, BINSIZE = binsize, MAXV = MAXV, MINV = MINV, $
  7.     TOP = top, HISTOGRAM_ONLY=histogram_only
  8. ;
  9. ;+
  10. ; NAME:
  11. ;    HIST_EQUAL
  12. ;
  13. ; PURPOSE:
  14. ;    Return a histogram-equalized image or vector.
  15. ;
  16. ; CATEGORY:
  17. ;    Z1 - Image processing, spatially invariant.
  18. ;
  19. ; CALLING SEQUENCE:
  20. ;    Result = HIST_EQUAL(A [, MINV = minv] [, MAXV = maxv])
  21. ;
  22. ; INPUTS:
  23. ;    A:    The array to be histogram-equalized.
  24. ;
  25. ; KEYWORD PARAMETERS:
  26. ;     BINSIZE:    Size of bin to use.  If this keyword is omitted, the value 1
  27. ;        is used.  Ignored for byte type data.  Default = approx 5000
  28. ;        bins for floating or double data.  For integer data
  29. ;        default is the smaller of the data range and 5000.
  30. ;
  31. ;    HISTOGRAM_ONLY: If set, return the cumulative distribution histogram,
  32. ;        rather than the histogram equalized array.  MAXV, MINV, and
  33. ;        BINSIZE will be set, describing the scaling of the histogram,
  34. ;        if not specified.
  35. ;    MAXV:    The maximum value to consider.  If this keyword is omitted,
  36. ;        the maximum element is used.  Input elements greater than or
  37. ;        equal to MAXV are output as 255.
  38. ;
  39. ;    MINV:    The minimum value to consider.  If this keyword is omitted,
  40. ;        the minimum is computed. Input elements less than or equal
  41. ;        to MINV are output as zero.
  42. ;
  43. ;    TOP:    The maximum value to scale the output array. If this keyword 
  44. ;        is omitted, 255 is used.
  45. ;
  46. ; OUTPUTS:
  47. ;    A histogram-equalized byte array is returned.
  48. ;
  49. ; COMMON BLOCKS:
  50. ;    None.
  51. ;
  52. ; SIDE EFFECTS:
  53. ;    None.
  54. ;
  55. ; RESTRICTIONS:
  56. ;    The output array is always of byte type and is scaled from 0 to TOP. 
  57. ;    Floating-point arrays should not have small ranges, (e.g., less than
  58. ;    around 255) unless a binsize is specified.
  59. ;
  60. ; PROCEDURE:
  61. ;    The HISTOGRAM function is used to obtain the density distribution of
  62. ;    the input array.  The histogram is integrated to obtain the 
  63. ;    cumulative density-propability function and finally the lookup 
  64. ;    function is used to transform to the output image.
  65. ;
  66. ;    The first element of the histogram is always zeroed, to remove
  67. ;    the background.
  68. ; EXAMPLE:
  69. ;    Create a sample image using the IDL DIST function and display it by
  70. ;    entering:
  71. ;
  72. ;        IMAGE = DIST(100)
  73. ;        TV, DIST
  74. ;    
  75. ;    Create a histogram-equalized version of the byte array, IMAGE, and
  76. ;    display the new version.  Use a minumum input value of 10, a maximum 
  77. ;    input value of 200, and limit the top value of the output array to 
  78. ;    220.  Enter:
  79. ;
  80. ;        NEW = HIST_EQUAL(IMAGE, MINV = 10, MAXV = 200, TOP = 220)
  81. ;        TV, NEW 
  82. ;
  83. ; MODIFICATION HISTORY:
  84. ;    August, 1982. Written by DMS, RSI.
  85. ;    Feb, 1988, Revised for Sun, DMS.
  86. ;    Dec, 1994. DMS. Improved handling offloating/double images with
  87. ;            large or small ranges.  Default value for MINV is
  88. ;            computed, rather than set to 0.
  89. ;    Oct, 1996. DMS. Made the handling of MIN=, and MAX= consistent
  90. ;            for all data types.
  91. ;-
  92. ;
  93.     on_error,2                        ;Return to caller if an error occurs
  94.     if n_elements(top) eq 0 then top = 255
  95.     S = SIZE(A)        ;Type of var?
  96.     type = s[s[0]+1]
  97.  
  98.     If type eq 1 then begin    ;byte var?
  99.         if n_elements(binsize) le 0 then binsize = 1
  100.         p = histogram(a, binsize = binsize)
  101.         p[0]=0
  102.         if n_elements(minv) eq 0 then minv = 0
  103.                 if n_elements(maxv) eq 0 then maxv = 255
  104.                 if maxv le minv then $
  105.                   message,'Image max is equal to min, or illegal range'
  106.                 if minv gt 0 then p[0:minv] = 0
  107.                 if maxv lt 255 then p[maxv+1:*] = 0
  108.         for i=1, n_elements(p)-1 do p[i]=p[i]+p[i-1] ;integrate
  109.         if keyword_set(histogram_only) then return, p
  110.         P=bytscl(p,top=top)
  111.         RETURN,P[A]            ;Transform & return.
  112.             endif else begin
  113.                 if n_elements(maxv) eq 0 or n_elements(minv) eq 0 then $
  114.                   dmin = min(a, max=dmax) ;Get data range
  115.                 if n_elements(maxv) le 0 then maxv = dmax
  116.                 if n_elements(minv) le 0 then minv = dmin
  117.                 if maxv le minv then $
  118.                   message,'Image max is equal to min, or illegal range'
  119.                 if n_elements(binsize) eq 0 then begin ;Calc binsize?
  120.                     if type le 3 then $ ;Ints?
  121.                       binsize = CEIL((long(maxv)-long(minv)) / 5000.) > 1 $
  122.                     else if type le 5 then $ ;Floating or double
  123.                       binsize = (maxv-minv) / 5000. $
  124.                     else message,'Complex images not allowed'
  125.                 endif           ;Binsize
  126.         p = histogram(a, MIN=minv, MAX = maxv, BINSIZE=binsize)
  127.         p[0] = 0
  128.         for i=1L,n_elements(p)-1 do p[i]=p[i]+p[i-1] ;Cumul. integral
  129.         if keyword_set(histogram_only) then return, p
  130.         P=bytscl(p, top = top)
  131.         if binsize eq 1 then begin
  132.             if minv eq 0 then return,p[a] else RETURN,P[A-minv]
  133.         endif else begin
  134.             if minv eq 0 then return, p[a/binsize] else $
  135.             return, P[(a-minv)/binsize]
  136.         endelse
  137.     endelse
  138. end
  139.